<?php
/**
 * Specifies the base functionality of all classes that are responsible for communicating
 * directly with this application's MySQL database to add, retrieve, update, and remove data,
 * as well as constructing the user interface elements to fit the user's circumstances.
 *
 * <p>
 * DataManager classes are assumed to represent a given entity that users (i.e. Agents and System
 * Administrators) of the Olive Insurance Client Management System desire to add, remove, modify to
 * their discretion. They are assumed to contain multiple variables that each represent data that these
 * users typically desire to add or modify; furthermore, this interface is designed with the assumption
 * that users prefer to have this data accessible and readily updated at all times to reflect all
 * data transactions.
 * </p>
 *
 * @author Darrius Serrant, Computer Science (Undergraduate)
 */
interface DataManager {

    /**
     * Updates a specific database table with the data stored in the class's data fields.
     */
    function update ( ) ;

    /**
     * Retrieves data from a specific database table that matches the given primary key value.
     * <p>
     * If the function successfully mathces the primary key to a specific record in the table, then
     * it will update all of the encapsulated data fields with the data retrieved from the database.
     * </p>
     *
     * @param primaryKey   the primary key value of the record to be retrieved from a given database table.
     * @return true if the query was successful, false otherwise.
     */
    function select ( $primaryKey ) ;

    /**
     * Creates a new record in a given database table for the data supplied in the paramaters.
     * <p>
     * Upon successful insertion, this class's data fields will be updated to match the data that was inserted
     * into the database.
     * </p>
     *
     * @param data    a comma-delimited string containing all the values to be inserted into the database.
     * @return true if the transaction was successful, false otherwise.
     */
    function insert ( $data ) ;

    /**
     * Removes a record from a specific database table that is associated with the primary key value provided
     * in the parameters.
     *
     * @param primaryKey   the primary key of the record to be retrieved from a given database table.
     * @return true if the transaction was successful, false otherwise.
     */
    function remove ( $primaryKey ) ;

    /**
     * Creates the XHTML form fields for the frontend to use to contain the user's input.
     * <p>
     * Before returning the form fields to the function's caller, it shall always populate the forms
     * initially with whatever data that it contains in its field variables.
     * </p>
     *
     * @return the extensible-hypertext-markup of the form fields to be used by the user interface to accept and validate
     * user input.
     */
    function getForm ( ) ;

    /**
     * Returns the error message associated with the most recently-failed transaction.
     *
     * @return error message
     */
    function getErrorMessage ( ) ;
}
?>
